   This is an introduction to `Programming in Emacs Lisp', for people
who are not programmers.

   Edition 2.04, 2001 Dec 17

   Copyright (C) 1990, '91, '92, '93, '94, '95, '97, 2001 Free Software
Foundation, Inc.

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Section being the Preface, with the Front-Cover Texts being
no Front-Cover Texts, and with the Back-Cover Texts being no Back-Cover
Texts.  A copy of the license is included in the section entitled "GNU
Free Documentation License".

`save-excursion'
================

   The `save-excursion' function is the fourth and final special form
that we will discuss in this chapter.

   In Emacs Lisp programs used for editing, the `save-excursion'
function is very common.  It saves the location of point and mark,
executes the body of the function, and then restores point and mark to
their previous positions if their locations were changed.  Its primary
purpose is to keep the user from being surprised and disturbed by
unexpected movement of point or mark.

Point and Mark
--------------

   Before discussing `save-excursion', however, it may be useful first
to review what point and mark are in GNU Emacs.  "Point" is the current
location of the cursor.  Wherever the cursor is, that is point.  More
precisely, on terminals where the cursor appears to be on top of a
character, point is immediately before the character.  In Emacs Lisp,
point is an integer.  The first character in a buffer is number one,
the second is number two, and so on.  The function `point' returns the
current position of the cursor as a number.  Each buffer has its own
value for point.

   The "mark" is another position in the buffer; its value can be set
with a command such as `C-<SPC>' (`set-mark-command').  If a mark has
been set, you can use the command `C-x C-x' (`exchange-point-and-mark')
to cause the cursor to jump to the mark and set the mark to be the
previous position of point.  In addition, if you set another mark, the
position of the previous mark is saved in the mark ring.  Many mark
positions can be saved this way.  You can jump the cursor to a saved
mark by typing `C-u C-<SPC>' one or more times.

   The part of the buffer between point and mark is called "the
region".  Numerous commands work on the region, including
`center-region', `count-lines-region', `kill-region', and
`print-region'.

   The `save-excursion' special form saves the locations of point and
mark and restores those positions after the code within the body of the
special form is evaluated by the Lisp interpreter.  Thus, if point were
in the beginning of a piece of text and some code moved point to the end
of the buffer, the `save-excursion' would put point back to where it
was before, after the expressions in the body of the function were
evaluated.

   In Emacs, a function frequently moves point as part of its internal
workings even though a user would not expect this.  For example,
`count-lines-region' moves point.  To prevent the user from being
bothered by jumps that are both unexpected and (from the user's point of
view) unnecessary, `save-excursion' is often used to keep point and
mark in the location expected by the user.  The use of `save-excursion'
is good housekeeping.

   To make sure the house stays clean, `save-excursion' restores the
values of point and mark even if something goes wrong in the code inside
of it (or, to be more precise and to use the proper jargon, "in case of
abnormal exit").  This feature is very helpful.

   In addition to recording the values of point and mark,
`save-excursion' keeps track of the current buffer, and restores it,
too.  This means you can write code that will change the buffer and
have `save-excursion' switch you back to the original buffer.  This is
how `save-excursion' is used in `append-to-buffer'.  (see The Definition of `append-to-buffer'.)

Template for a `save-excursion' Expression
------------------------------------------

   The template for code using `save-excursion' is simple:

     (save-excursion
       BODY...)

The body of the function is one or more expressions that will be
evaluated in sequence by the Lisp interpreter.  If there is more than
one expression in the body, the value of the last one will be returned
as the value of the `save-excursion' function.  The other expressions
in the body are evaluated only for their side effects; and
`save-excursion' itself is used only for its side effect (which is
restoring the positions of point and mark).

   In more detail, the template for a `save-excursion' expression looks
like this:

     (save-excursion
       FIRST-EXPRESSION-IN-BODY
       SECOND-EXPRESSION-IN-BODY
       THIRD-EXPRESSION-IN-BODY
        ...
       LAST-EXPRESSION-IN-BODY)

An expression, of course, may be a symbol on its own or a list.

   In Emacs Lisp code, a `save-excursion' expression often occurs
within the body of a `let' expression.  It looks like this:

     (let VARLIST
       (save-excursion
         BODY...))

Review
======

   In the last few chapters we have introduced a fair number of
functions and special forms.  Here they are described in brief, along
with a few similar functions that have not been mentioned yet.

`eval-last-sexp'
     Evaluate the last symbolic expression before the current location
     of point.  The value is printed in the echo area unless the
     function is invoked with an argument; in that case, the output is
     printed in the current buffer.  This command is normally bound to
     `C-x C-e'.

`defun'
     Define function.  This special form has up to five parts: the name,
     a template for the arguments that will be passed to the function,
     documentation, an optional interactive declaration, and the body
     of the definition.

     For example:

          (defun back-to-indentation ()
            "Move point to first visible character on line."
            (interactive)
            (beginning-of-line 1)
            (skip-chars-forward " \t"))

`interactive'
     Declare to the interpreter that the function can be used
     interactively.  This special form may be followed by a string with
     one or more parts that pass the information to the arguments of the
     function, in sequence.  These parts may also tell the interpreter
     to prompt for information.  Parts of the string are separated by
     newlines, `\n'.

     Common code characters are:

    `b'
          The name of an existing buffer.

    `f'
          The name of an existing file.

    `p'
          The numeric prefix argument.  (Note that this `p' is lower
          case.)

    `r'
          Point and the mark, as two numeric arguments, smallest first.
          This is the only code letter that specifies two successive
          arguments rather than one.

     See Code Characters for `interactive' (elisp),
     for a complete list of code characters.

`let'
     Declare that a list of variables is for use within the body of the
     `let' and give them an initial value, either `nil' or a specified
     value; then evaluate the rest of the expressions in the body of
     the `let' and return the value of the last one.  Inside the body
     of the `let', the Lisp interpreter does not see the values of the
     variables of the same names that are bound outside of the `let'.

     For example,

          (let ((foo (buffer-name))
                (bar (buffer-size)))
            (message
             "This buffer is %s and has %d characters."
             foo bar))

`save-excursion'
     Record the values of point and mark and the current buffer before
     evaluating the body of this special form.  Restore the values of
     point and mark and buffer afterward.

     For example,

          (message "We are %d characters into this buffer."
                   (- (point)
                      (save-excursion
                        (goto-char (point-min)) (point))))

`if'
     Evaluate the first argument to the function; if it is true,
     evaluate the second argument; else evaluate the third argument, if
     there is one.

     The `if' special form is called a "conditional".  There are other
     conditionals in Emacs Lisp, but `if' is perhaps the most commonly
     used.

     For example,

          (if (string-equal
               (number-to-string 21)
               (substring (emacs-version) 10 12))
              (message "This is version 21 Emacs")
            (message "This is not version 21 Emacs"))

`equal'
`eq'
     Test whether two objects are the same.  `equal' uses one meaning
     of the word `same' and `eq' uses another:  `equal' returns true if
     the two objects have a similar structure and contents, such as two
     copies of the same book.  On the other hand, `eq', returns true if
     both arguments are actually the same object.

`<'
`>'
`<='
`>='
     The `<' function tests whether its first argument is smaller than
     its second argument.  A corresponding function, `>', tests whether
     the first argument is greater than the second.  Likewise, `<='
     tests whether the first argument is less than or equal to the
     second and `>=' tests whether the first argument is greater than
     or equal to the second.  In all cases, both arguments must be
     numbers or markers (markers indicate positions in buffers).

`string<'
`string-lessp'
`string='
`string-equal'
     The `string-lessp' function tests whether its first argument is
     smaller than the second argument.  A shorter, alternative name for
     the same function (a `defalias') is `string<'.

     The arguments to `string-lessp' must be strings or symbols; the
     ordering is lexicographic, so case is significant.  The print
     names of symbols are used instead of the symbols themselves.

     An empty string, `""', a string with no characters in it, is
     smaller than any string of characters.

     `string-equal' provides the corresponding test for equality.  Its
     shorter, alternative name is `string='.  There are no string test
     functions that correspond to >, `>=', or `<='.

`message'
     Print a message in the echo area. The first argument is a string
     that can contain `%s', `%d', or `%c' to print the value of
     arguments that follow the string.  The argument used by `%s' must
     be a string or a symbol; the argument used by `%d' must be a
     number.  The argument used by `%c' must be an ascii code number;
     it will be printed as the character with that ASCII code.

`setq'
`set'
     The `setq' function sets the value of its first argument to the
     value of the second argument.  The first argument is automatically
     quoted by `setq'.  It does the same for succeeding pairs of
     arguments.  Another function, `set', takes only two arguments and
     evaluates both of them before setting the value returned by its
     first argument to the value returned by its second argument.

`buffer-name'
     Without an argument, return the name of the buffer, as a string.

`buffer-file-name'
     Without an argument, return the name of the file the buffer is
     visiting.

`current-buffer'
     Return the buffer in which Emacs is active; it may not be the
     buffer that is visible on the screen.

`other-buffer'
     Return the most recently selected buffer (other than the buffer
     passed to `other-buffer' as an argument and other than the current
     buffer).

`switch-to-buffer'
     Select a buffer for Emacs to be active in and display it in the
     current window so users can look at it.  Usually bound to `C-x b'.

`set-buffer'
     Switch Emacs' attention to a buffer on which programs will run.
     Don't alter what the window is showing.

`buffer-size'
     Return the number of characters in the current buffer.

`point'
     Return the value of the current position of the cursor, as an
     integer counting the number of characters from the beginning of the
     buffer.

`point-min'
     Return the minimum permissible value of point in the current
     buffer.  This is 1, unless narrowing is in effect.

`point-max'
     Return the value of the maximum permissible value of point in the
     current buffer.  This is the end of the buffer, unless narrowing
     is in effect.

Exercises
=========

   * Write a non-interactive function that doubles the value of its
     argument, a number.  Make that function interactive.

   * Write a function that tests whether the current value of
     `fill-column' is greater than the argument passed to the function,
     and if so, prints an appropriate message.

A Few Buffer-Related Functions
******************************

   In this chapter we study in detail several of the functions used in
GNU Emacs.  This is called a "walk-through".  These functions are used
as examples of Lisp code, but are not imaginary examples; with the
exception of the first, simplified function definition, these functions
show the actual code used in GNU Emacs.  You can learn a great deal from
these definitions.  The functions described here are all related to
buffers.  Later, we will study other functions.

Finding More Information
========================

   In this walk-through, I will describe each new function as we come to
it, sometimes in detail and sometimes briefly.  If you are interested,
you can get the full documentation of any Emacs Lisp function at any
time by typing `C-h f' and then the name of the function (and then
<RET>).  Similarly, you can get the full documentation for a variable
by typing `C-h v' and then the name of the variable (and then <RET>).

   In versions 20 and higher, when a function is written in Emacs Lisp,
`describe-function' will also tell you the location of the function
definition.  If you move point over the file name and press the <RET>
key, which is this case means `help-follow' rather than `return' or
`enter', Emacs will take you directly to the function definition.

   More generally, if you want to see a function in its original source
file, you can use the `find-tags' function to jump to it.  `find-tags'
works with a wide variety of languages, not just Lisp, and C, and it
works with non-programming text as well.  For example, `find-tags' will
jump to the various nodes in the Texinfo source file of this document.

   The `find-tags' function depends on `tags tables' that record the
locations of the functions, variables, and other items to which
`find-tags' jumps.

   To use the `find-tags' command, type `M-.'  (i.e., type the <META>
key and the period key at the same time, or else type the <ESC> key and
then type the period key), and then, at the prompt, type in the name of
the function whose source code you want to see, such as
`mark-whole-buffer', and then type <RET>.  Emacs will switch buffers
and display the source code for the function on your screen.  To switch
back to your current buffer, type `C-x b <RET>'.  (On some keyboards,
the <META> key is labelled <ALT>.)

   Depending on how the initial default values of your copy of Emacs are
set, you may also need to specify the location of your `tags table',
which is a file called `TAGS'.  For example, if you are interested in
Emacs sources, the tags table you will most likely want, if it has
already been created for you, will be in a subdirectory of the
`/usr/local/share/emacs/' directory; thus you would use the `M-x
visit-tags-table' command and specify a pathname such as
`/usr/local/share/emacs/21.0.100/lisp/TAGS' or
`/usr/local/src/emacs/lisp/TAGS'.  If the tags table has not already
been created, you will have to create it yourself.

   To create a `TAGS' file in a specific directory, switch to that
directory in Emacs using `M-x cd' command, or list the directory with
`C-x d' (`dired').  Then run the compile command, with `etags *.el' as
the command to execute

     M-x compile RET etags *.el RET

   For more information, see Create Your Own `TAGS' File.

   After you become more familiar with Emacs Lisp, you will find that
you will frequently use `find-tags' to navigate your way around source
code; and you will create your own `TAGS' tables.

   Incidentally, the files that contain Lisp code are conventionally
called "libraries".  The metaphor is derived from that of a specialized
library, such as a law library or an engineering library, rather than a
general library.  Each library, or file, contains functions that relate
to a particular topic or activity, such as `abbrev.el' for handling
abbreviations and other typing shortcuts, and `help.el' for on-line
help.  (Sometimes several libraries provide code for a single activity,
as the various `rmail...' files provide code for reading electronic
mail.)  In `The GNU Emacs Manual', you will see sentences such as "The
`C-h p' command lets you search the standard Emacs Lisp libraries by
topic keywords."

A Simplified `beginning-of-buffer' Definition
=============================================

   The `beginning-of-buffer' command is a good function to start with
since you are likely to be familiar with it and it is easy to
understand.  Used as an interactive command, `beginning-of-buffer'
moves the cursor to the beginning of the buffer, leaving the mark at the
previous position.  It is generally bound to `M-<'.

   In this section, we will discuss a shortened version of the function
that shows how it is most frequently used.  This shortened function
works as written, but it does not contain the code for a complex option.
In another section, we will describe the entire function.  (see
Complete Definition of `beginning-of-buffer'.)

   Before looking at the code, let's consider what the function
definition has to contain: it must include an expression that makes the
function interactive so it can be called by typing `M-x
beginning-of-buffer' or by typing a keychord such as `C-<'; it must
include code to leave a mark at the original position in the buffer;
and it must include code to move the cursor to the beginning of the
buffer.

   Here is the complete text of the shortened version of the function:

     (defun simplified-beginning-of-buffer ()
       "Move point to the beginning of the buffer;
     leave mark at previous position."
       (interactive)
       (push-mark)
       (goto-char (point-min)))

   Like all function definitions, this definition has five parts
following the special form `defun':

  1. The name: in this example, `simplified-beginning-of-buffer'.

  2. A list of the arguments: in this example, an empty list, `()',

  3. The documentation string.

  4. The interactive expression.

  5. The body.

In this function definition, the argument list is empty; this means that
this function does not require any arguments.  (When we look at the
definition for the complete function, we will see that it may be passed
an optional argument.)

   The interactive expression tells Emacs that the function is intended
to be used interactively.  In this example, `interactive' does not have
an argument because `simplified-beginning-of-buffer' does not require
one.

   The body of the function consists of the two lines:

     (push-mark)
     (goto-char (point-min))

   The first of these lines is the expression, `(push-mark)'.  When
this expression is evaluated by the Lisp interpreter, it sets a mark at
the current position of the cursor, wherever that may be.  The position
of this mark is saved in the mark ring.

   The next line is `(goto-char (point-min))'.  This expression jumps
the cursor to the minimum point in the buffer, that is, to the
beginning of the buffer (or to the beginning of the accessible portion
of the buffer if it is narrowed.  See Narrowing and Widening.)

   The `push-mark' command sets a mark at the place where the cursor
was located before it was moved to the beginning of the buffer by the
`(goto-char (point-min))' expression.  Consequently, you can, if you
wish, go back to where you were originally by typing `C-x C-x'.

   That is all there is to the function definition!

   When you are reading code such as this and come upon an unfamiliar
function, such as `goto-char', you can find out what it does by using
the `describe-function' command.  To use this command, type `C-h f' and
then type in the name of the function and press <RET>.  The
`describe-function' command will print the function's documentation
string in a `*Help*' window.  For example, the documentation for
`goto-char' is:

     One arg, a number.  Set point to that number.
     Beginning of buffer is position (point-min),
     end is (point-max).

(The prompt for `describe-function' will offer you the symbol under or
preceding the cursor, so you can save typing by positioning the cursor
right over or after the function and then typing `C-h f <RET>'.)

   The `end-of-buffer' function definition is written in the same way as
the `beginning-of-buffer' definition except that the body of the
function contains the expression `(goto-char (point-max))' in place of
`(goto-char (point-min))'.

The Definition of `mark-whole-buffer'
=====================================

   The `mark-whole-buffer' function is no harder to understand than the
`simplified-beginning-of-buffer' function.  In this case, however, we
will look at the complete function, not a shortened version.

   The `mark-whole-buffer' function is not as commonly used as the
`beginning-of-buffer' function, but is useful nonetheless: it marks a
whole buffer as a region by putting point at the beginning and a mark
at the end of the buffer.  It is generally bound to `C-x h'.

An overview of `mark-whole-buffer'
----------------------------------

   In GNU Emacs 20, the code for the complete function looks like this:

     (defun mark-whole-buffer ()
       "Put point at beginning and mark at end of buffer."
       (interactive)
       (push-mark (point))
       (push-mark (point-max))
       (goto-char (point-min)))

   Like all other functions, the `mark-whole-buffer' function fits into
the template for a function definition.  The template looks like this:

     (defun NAME-OF-FUNCTION (ARGUMENT-LIST)
       "DOCUMENTATION..."
       (INTERACTIVE-EXPRESSION...)
       BODY...)

   Here is how the function works: the name of the function is
`mark-whole-buffer'; it is followed by an empty argument list, `()',
which means that the function does not require arguments.  The
documentation comes next.

   The next line is an `(interactive)' expression that tells Emacs that
the function will be used interactively.  These details are similar to
the `simplified-beginning-of-buffer' function described in the previous
section.

Body of `mark-whole-buffer'
---------------------------

   The body of the `mark-whole-buffer' function consists of three lines
of code:

     (push-mark (point))
     (push-mark (point-max))
     (goto-char (point-min))

   The first of these lines is the expression, `(push-mark (point))'.

   This line does exactly the same job as the first line of the body of
the `simplified-beginning-of-buffer' function, which is written
`(push-mark)'.  In both cases, the Lisp interpreter sets a mark at the
current position of the cursor.

   I don't know why the expression in `mark-whole-buffer' is written
`(push-mark (point))' and the expression in `beginning-of-buffer' is
written `(push-mark)'.  Perhaps whoever wrote the code did not know
that the arguments for `push-mark' are optional and that if `push-mark'
is not passed an argument, the function automatically sets mark at the
location of point by default.  Or perhaps the expression was written so
as to parallel the structure of the next line.  In any case, the line
causes Emacs to determine the position of point and set a mark there.

   The next line of `mark-whole-buffer' is `(push-mark (point-max)'.
This expression sets a mark at the point in the buffer that has the
highest number.  This will be the end of the buffer (or, if the buffer
is narrowed, the end of the accessible portion of the buffer.  See
Narrowing and Widening, for more about
narrowing.)  After this mark has been set, the previous mark, the one
set at point, is no longer set, but Emacs remembers its position, just
as all other recent marks are always remembered.  This means that you
can, if you wish, go back to that position by typing `C-u C-<SPC>'
twice.

   (In GNU Emacs 21, the `(push-mark (point-max)' is slightly more
complicated than shown here.  The line reads

     (push-mark (point-max) nil t)

(The expression works nearly the same as before.  It sets a mark at the
highest numbered place in the buffer that it can.  However, in this
version, `push-mark' has two additional arguments.  The second argument
to `push-mark' is `nil'.  This tells the function it _should_ display a
message that says `Mark set' when it pushes the mark.  The third
argument is `t'.  This tells `push-mark' to activate the mark when
Transient Mark mode is turned on.  Transient Mark mode highlights the
currently active region.  It is usually turned off.)

   Finally, the last line of the function is `(goto-char
(point-min)))'.  This is written exactly the same way as it is written
in `beginning-of-buffer'.  The expression moves the cursor to the
minimum point in the buffer, that is, to the beginning of the buffer
(or to the beginning of the accessible portion of the buffer).  As a
result of this, point is placed at the beginning of the buffer and mark
is set at the end of the buffer.  The whole buffer is, therefore, the
region.

The Definition of `append-to-buffer'
====================================

   The `append-to-buffer' command is very nearly as simple as the
`mark-whole-buffer' command.  What it does is copy the region (that is,
the part of the buffer between point and mark) from the current buffer
to a specified buffer.

An Overview of `append-to-buffer'
---------------------------------

   The `append-to-buffer' command uses the `insert-buffer-substring'
function to copy the region.  `insert-buffer-substring' is described by
its name: it takes a string of characters from part of a buffer, a
"substring", and inserts them into another buffer.  Most of
`append-to-buffer' is concerned with setting up the conditions for
`insert-buffer-substring' to work: the code must specify both the
buffer to which the text will go and the region that will be copied.
Here is the complete text of the function:

     (defun append-to-buffer (buffer start end)
       "Append to specified buffer the text of the region.
     It is inserted into that buffer before its point.

     When calling from a program, give three arguments:
     a buffer or the name of one, and two character numbers
     specifying the portion of the current buffer to be copied."
       (interactive "BAppend to buffer: \nr")
       (let ((oldbuf (current-buffer)))
         (save-excursion
           (set-buffer (get-buffer-create buffer))
           (insert-buffer-substring oldbuf start end))))

   The function can be understood by looking at it as a series of
filled-in templates.

   The outermost template is for the function definition.  In this
function, it looks like this (with several slots filled in):

     (defun append-to-buffer (buffer start end)
       "DOCUMENTATION..."
       (interactive "BAppend to buffer: \nr")
       BODY...)

   The first line of the function includes its name and three arguments.
The arguments are the `buffer' to which the text will be copied, and
the `start' and `end' of the region in the current buffer that will be
copied.

   The next part of the function is the documentation, which is clear
and complete.

The `append-to-buffer' Interactive Expression
---------------------------------------------

   Since the `append-to-buffer' function will be used interactively,
the function must have an `interactive' expression.  (For a review of
`interactive', see Making a Function Interactive.)
The expression reads as follows:

     (interactive "BAppend to buffer: \nr")

This expression has an argument inside of quotation marks and that
argument has two parts, separated by `\n'.

   The first part is `BAppend to buffer: '.  Here, the `B' tells Emacs
to ask for the name of the buffer that will be passed to the function.
Emacs will ask for the name by prompting the user in the minibuffer,
using the string following the `B', which is the string `Append to
buffer: '.  Emacs then binds the variable `buffer' in the function's
argument list to the specified buffer.

   The newline, `\n', separates the first part of the argument from the
second part.  It is followed by an `r' that tells Emacs to bind the two
arguments that follow the symbol `buffer' in the function's argument
list (that is, `start' and `end') to the values of point and mark.

The Body of `append-to-buffer'
------------------------------

   The body of the `append-to-buffer' function begins with `let'.

   As we have seen before (see `let'), the purpose of a `let'
expression is to create and give initial values to one or more
variables that will only be used within the body of the `let'.  This
means that such a variable will not be confused with any variable of
the same name outside the `let' expression.

   We can see how the `let' expression fits into the function as a
whole by showing a template for `append-to-buffer' with the `let'
expression in outline:

     (defun append-to-buffer (buffer start end)
       "DOCUMENTATION..."
       (interactive "BAppend to buffer: \nr")
       (let ((VARIABLE VALUE))
             BODY...)

   The `let' expression has three elements:

  1. The symbol `let';

  2. A varlist containing, in this case, a single two-element list,
     `(VARIABLE VALUE)';

  3. The body of the `let' expression.

   In the `append-to-buffer' function, the varlist looks like this:

     (oldbuf (current-buffer))

In this part of the `let' expression, the one variable, `oldbuf', is
bound to the value returned by the `(current-buffer)' expression.  The
variable, `oldbuf', is used to keep track of the buffer in which you
are working and from which you will copy.

   The element or elements of a varlist are surrounded by a set of
parentheses so the Lisp interpreter can distinguish the varlist from
the body of the `let'.  As a consequence, the two-element list within
the varlist is surrounded by a circumscribing set of parentheses.  The
line looks like this:

     (let ((oldbuf (current-buffer)))
       ... )

The two parentheses before `oldbuf' might surprise you if you did not
realize that the first parenthesis before `oldbuf' marks the boundary
of the varlist and the second parenthesis marks the beginning of the
two-element list, `(oldbuf (current-buffer))'.

`save-excursion' in `append-to-buffer'
--------------------------------------

   The body of the `let' expression in `append-to-buffer' consists of a
`save-excursion' expression.

   The `save-excursion' function saves the locations of point and mark,
and restores them to those positions after the expressions in the body
of the `save-excursion' complete execution.  In addition,
`save-excursion' keeps track of the original buffer, and restores it.
This is how `save-excursion' is used in `append-to-buffer'.

   Incidentally, it is worth noting here that a Lisp function is
normally formatted so that everything that is enclosed in a multi-line
spread is indented more to the right than the first symbol.  In this
function definition, the `let' is indented more than the `defun', and
the `save-excursion' is indented more than the `let', like this:

     (defun ...
       ...
       ...
       (let...
         (save-excursion
           ...

This formatting convention makes it easy to see that the two lines in
the body of the `save-excursion' are enclosed by the parentheses
associated with `save-excursion', just as the `save-excursion' itself
is enclosed by the parentheses associated with the `let':

     (let ((oldbuf (current-buffer)))
       (save-excursion
         (set-buffer (get-buffer-create buffer))
         (insert-buffer-substring oldbuf start end))))

   The use of the `save-excursion' function can be viewed as a process
of filling in the slots of a template:

     (save-excursion
       FIRST-EXPRESSION-IN-BODY
       SECOND-EXPRESSION-IN-BODY
        ...
       LAST-EXPRESSION-IN-BODY)

In this function, the body of the `save-excursion' contains only two
expressions.  The body looks like this:

     (set-buffer (get-buffer-create buffer))
     (insert-buffer-substring oldbuf start end)

   When the `append-to-buffer' function is evaluated, the two
expressions in the body of the `save-excursion' are evaluated in
sequence.  The value of the last expression is returned as the value of
the `save-excursion' function; the other expression is evaluated only
for its side effects.

   The first line in the body of the `save-excursion' uses the
`set-buffer' function to change the current buffer to the one specified
in the first argument to `append-to-buffer'.  (Changing the buffer is
the side effect; as we have said before, in Lisp, a side effect is
often the primary thing we want.)  The second line does the primary
work of the function.

   The `set-buffer' function changes Emacs' attention to the buffer to
which the text will be copied and from which `save-excursion' will
return.

   The line looks like this:

     (set-buffer (get-buffer-create buffer))

   The innermost expression of this list is `(get-buffer-create
buffer)'.  This expression uses the `get-buffer-create' function, which
either gets the named buffer, or if it does not exist, creates one with
the given name.  This means you can use `append-to-buffer' to put text
into a buffer that did not previously exist.

   `get-buffer-create' also keeps `set-buffer' from getting an
unnecessary error: `set-buffer' needs a buffer to go to; if you were to
specify a buffer that does not exist, Emacs would baulk.  Since
`get-buffer-create' will create a buffer if none exists, `set-buffer'
is always provided with a buffer.

   The last line of `append-to-buffer' does the work of appending the
text:

     (insert-buffer-substring oldbuf start end)

The `insert-buffer-substring' function copies a string _from_ the
buffer specified as its first argument and inserts the string into the
present buffer.  In this case, the argument to
`insert-buffer-substring' is the value of the variable created and
bound by the `let', namely the value of `oldbuf', which was the current
buffer when you gave the `append-to-buffer' command.

   After `insert-buffer-substring' has done its work, `save-excursion'
will restore the action to the original buffer and `append-to-buffer'
will have done its job.

   Written in skeletal form, the workings of the body look like this:

     (let (BIND-`oldbuf'-TO-VALUE-OF-`current-buffer')
       (save-excursion                       ; Keep track of buffer.
         CHANGE-BUFFER
         INSERT-SUBSTRING-FROM-`oldbuf'-INTO-BUFFER)

       CHANGE-BACK-TO-ORIGINAL-BUFFER-WHEN-FINISHED
     LET-THE-LOCAL-MEANING-OF-`oldbuf'-DISAPPEAR-WHEN-FINISHED

   In summary, `append-to-buffer' works as follows: it saves the value
of the current buffer in the variable called `oldbuf'.  It gets the new
buffer, creating one if need be, and switches Emacs to it.  Using the
value of `oldbuf', it inserts the region of text from the old buffer
into the new buffer; and then using `save-excursion', it brings you
back to your original buffer.

   In looking at `append-to-buffer', you have explored a fairly complex
function.  It shows how to use `let' and `save-excursion', and how to
change to and come back from another buffer.  Many function definitions
use `let', `save-excursion', and `set-buffer' this way.

Review
======

   Here is a brief summary of the various functions discussed in this
chapter.

`describe-function'
`describe-variable'
     Print the documentation for a function or variable.
     Conventionally bound to `C-h f' and `C-h v'.

`find-tag'
     Find the file containing the source for a function or variable and
     switch buffers to it, positioning point at the beginning of the
     item.  Conventionally bound to `M-.' (that's a period following the
     <META> key).

`save-excursion'
     Save the location of point and mark and restore their values after
     the arguments to `save-excursion' have been evaluated.  Also,
     remember the current buffer and return to it.

`push-mark'
     Set mark at a location and record the value of the previous mark
     on the mark ring.  The mark is a location in the buffer that will
     keep its relative position even if text is added to or removed
     from the buffer.

`goto-char'
     Set point to the location specified by the value of the argument,
     which can be a number, a marker,  or an expression that returns
     the number of a position, such as `(point-min)'.

`insert-buffer-substring'
     Copy a region of text from a buffer that is passed to the function
     as an argument and insert the region into the current buffer.

`mark-whole-buffer'
     Mark the whole buffer as a region.  Normally bound to `C-x h'.

`set-buffer'
     Switch the attention of Emacs to another buffer, but do not change
     the window being displayed.  Used when the program rather than a
     human is to work on a different buffer.

`get-buffer-create'
`get-buffer'
     Find a named buffer or create one if a buffer of that name does not
     exist.  The `get-buffer' function returns `nil' if the named
     buffer does not exist.

Exercises
=========

   * Write your own `simplified-end-of-buffer' function definition;
     then test it to see whether it works.

   * Use `if' and `get-buffer' to write a function that prints a
     message telling you whether a buffer exists.

   * Using `find-tag', find the source for the `copy-to-buffer'
     function.

A Few More Complex Functions
****************************

   In this chapter, we build on what we have learned in previous
chapters by looking at more complex functions.  The `copy-to-buffer'
function illustrates use of two `save-excursion' expressions in one
definition, while the `insert-buffer' function illustrates use of an
asterisk in an `interactive' expression, use of `or', and the important
distinction between a name and the object to which the name refers.

The Definition of `copy-to-buffer'
==================================

   After understanding how `append-to-buffer' works, it is easy to
understand `copy-to-buffer'.  This function copies text into a buffer,
but instead of adding to the second buffer, it replaces the previous
text in the second buffer.  The code for the `copy-to-buffer' function
is almost the same as the code for `append-to-buffer', except that
`erase-buffer' and a second `save-excursion' are used.  (see The Definition of `append-to-buffer',
for the description
of `append-to-buffer'.)

   The body of `copy-to-buffer' looks like this

     ...
     (interactive "BCopy to buffer: \nr")
       (let ((oldbuf (current-buffer)))
         (save-excursion
           (set-buffer (get-buffer-create buffer))
           (erase-buffer)
           (save-excursion
             (insert-buffer-substring oldbuf start end)))))

   This code is similar to the code in `append-to-buffer': it is only
after changing to the buffer to which the text will be copied that the
definition for this function diverges from the definition for
`append-to-buffer': the `copy-to-buffer' function erases the buffer's
former contents.  (This is what is meant by `replacement'; to replace
text, Emacs erases the previous text and then inserts new text.)  After
erasing the previous contents of the buffer, `save-excursion' is used
for a second time and the new text is inserted.

   Why is `save-excursion' used twice?  Consider again what the
function does.

   In outline, the body of `copy-to-buffer' looks like this:

     (let (BIND-`oldbuf'-TO-VALUE-OF-`current-buffer')
       (save-excursion         ; First use of `save-excursion'.
         CHANGE-BUFFER
           (erase-buffer)
           (save-excursion     ; Second use of `save-excursion'.
             INSERT-SUBSTRING-FROM-`oldbuf'-INTO-BUFFER)))

   The first use of `save-excursion' returns Emacs to the buffer from
which the text is being copied.  That is clear, and is just like its use
in `append-to-buffer'.  Why the second use?  The reason is that
`insert-buffer-substring' always leaves point at the _end_ of the
region being inserted.  The second `save-excursion' causes Emacs to
leave point at the beginning of the text being inserted.  In most
circumstances, users prefer to find point at the beginning of inserted
text.  (Of course, the `copy-to-buffer' function returns the user to
the original buffer when done--but if the user _then_ switches to the
copied-to buffer, point will go to the beginning of the text.  Thus,
this use of a second `save-excursion' is a little nicety.)

The Definition of `insert-buffer'
=================================

   `insert-buffer' is yet another buffer-related function.  This
command copies another buffer _into_ the current buffer.  It is the
reverse of `append-to-buffer' or `copy-to-buffer', since they copy a
region of text _from_ the current buffer to another buffer.

   In addition, this code illustrates the use of `interactive' with a
buffer that might be "read-only" and the important distinction between
the name of an object and the object actually referred to.

The Code for `insert-buffer'
----------------------------

   Here is the code:

     (defun insert-buffer (buffer)
       "Insert after point the contents of BUFFER.
     Puts mark after the inserted text.
     BUFFER may be a buffer or a buffer name."
       (interactive "*bInsert buffer: ")
       (or (bufferp buffer)
           (setq buffer (get-buffer buffer)))
       (let (start end newmark)
         (save-excursion
           (save-excursion
             (set-buffer buffer)
             (setq start (point-min) end (point-max)))
           (insert-buffer-substring buffer start end)
           (setq newmark (point)))
         (push-mark newmark)))

   As with other function definitions, you can use a template to see an
outline of the function:

     (defun insert-buffer (buffer)
       "DOCUMENTATION..."
       (interactive "*bInsert buffer: ")
       BODY...)

The Interactive Expression in `insert-buffer'
---------------------------------------------

   In `insert-buffer', the argument to the `interactive' declaration
has two parts, an asterisk, `*', and `bInsert buffer: '.

A Read-only Buffer
..................

   The asterisk is for the situation when the buffer is a read-only
buffer--a buffer that cannot be modified.  If `insert-buffer' is called
on a buffer that is read-only, a message to this effect is printed in
the echo area and the terminal may beep or blink at you; you will not
be permitted to insert anything into current buffer.  The asterisk does
not need to be followed by a newline to separate it from the next
argument.

`b' in an Interactive Expression
................................

   The next argument in the interactive expression starts with a lower
case `b'.  (This is different from the code for `append-to-buffer',
which uses an upper-case `B'.  See The Definition of `append-to-buffer'.)
The lower-case `b' tells the
Lisp interpreter that the argument for `insert-buffer' should be an
existing buffer or else its name.  (The upper-case `B' option provides
for the possibility that the buffer does not exist.)  Emacs will prompt
you for the name of the buffer, offering you a default buffer, with
name completion enabled.  If the buffer does not exist, you receive a
message that says "No match"; your terminal may beep at you as well.

The Body of the `insert-buffer' Function
----------------------------------------

   The body of the `insert-buffer' function has two major parts: an
`or' expression and a `let' expression.  The purpose of the `or'
expression is to ensure that the argument `buffer' is bound to a buffer
and not just the name of a buffer.  The body of the `let' expression
contains the code which copies the other buffer into the current buffer.

   In outline, the two expressions fit into the `insert-buffer'
function like this:

     (defun insert-buffer (buffer)
       "DOCUMENTATION..."
       (interactive "*bInsert buffer: ")
       (or ...
           ...
       (let (VARLIST)
           BODY-OF-`let'... )

   To understand how the `or' expression ensures that the argument
`buffer' is bound to a buffer and not to the name of a buffer, it is
first necessary to understand the `or' function.

   Before doing this, let me rewrite this part of the function using
`if' so that you can see what is done in a manner that will be familiar.